home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / comms / other / slrn / slrn_src / slrnpull / readme < prev    next >
Text File  |  1999-05-14  |  7KB  |  178 lines
  1. See QUICK_INSTALL for minimal installation instructions.
  2. ----------------------------------------------------------------------
  3.  
  4. What is slrnpull?
  5. ==================
  6.  
  7. This version of slrn is capable of allowing a user to read offline.
  8. This is accomplished by using slrn in conjunction with the the
  9. slrnpull program.  Basically, slrnpull pulls a small newsfeed from an
  10. NNTP server from which slrn will subsequently read.
  11.  
  12. There are several other ``sucking'' programs available that perform a
  13. similar function as slrnpull.  The best known are `leafnode' and
  14. `suck'.  All of them, with the exception of `leafnode' require the
  15. user to run a newsserver program such as INN or CNEWS.  Like
  16. `leafnode', slrnpull does not require a newsserver. 
  17.  
  18. In many ways `leafnode' is more ambitious than `slrnpull'.  It was
  19. designed for many more readers and provides an nntp server to access
  20. the news spool.  However, I felt that even it was overkill for my
  21. purpose of pulling 10-20 newsgroups for myself.  For that reason, I
  22. wrote slrnpull.
  23.  
  24. slrnpull is very simple to setup and use.  It requires only one
  25. configuration file that is placed in its root news directory.  The
  26. purpose of the file is to specify which groups to download, how many
  27. articles should be downloaded at one time for a given newsgroup, and
  28. how many days can go by before an article will expire.  See
  29. slrnpull.conf file for an example and documentation for the format of
  30. the file.
  31.  
  32. slrnpull also has the ability to score articles so that they will not
  33. be downloaded from the server.  Unlike slrn, any article that is given
  34. a negative score by slrnpull will be killed; that is, it will not be
  35. retrieved from the server.
  36.  
  37.  
  38. slrnpull directory structure
  39. =============================
  40.  
  41. The directory structure assumed by slrnpull is as follows:
  42.  
  43.     SLRNPULL_ROOT/
  44.     SLRNPULL_ROOT/data
  45.     SLRNPULL_ROOT/news/
  46.     SLRNPULL_ROOT/out.going/
  47.     SLRNPULL_ROOT/out.going/rejects/
  48.  
  49. The actual news articles that are pulled from the server are placed in
  50. directories under the SLRNPULL_ROOT/news tree.  The out.going
  51. subdirectory is where posted articles will go until slrnpull sends
  52. them to the server.  Any article that is rejected by the server will
  53. be moved to the rejects subdirectory.  The files that slrnpull
  54. generates (active, new.groups, etc.) will be placed in the data
  55. subdirectory.
  56.  
  57. The configuration file, slrnpull.conf must be placed in the
  58. SLRNPULL_ROOT directory.  See the sample slrnpull.conf file for an
  59. explanation of the format of this file.  When slrnpull runs, it will
  60. read the slrnpull.conf file.  Based on the information present in that
  61. file, it will create the appropriate subdirectories under
  62. SLRNPULL_ROOT/news.
  63.  
  64. If your server requires authorization information, you will need to
  65. create a file called `authinfo' in the SLRNPULL_ROOT directory.  The
  66. file should consist of two lines.  The first line is for the username
  67. and the second line is for the password.
  68.  
  69. As slrnpull runs, it will append status and error messages to file
  70. called `log' in the SLRNPULL_ROOT directory.  You are advised to check
  71. this file after every run of slrnpull.  For example, if the server
  72. rejects a posted article, the log file will indicate this fact.
  73.  
  74. After slrnpull has grabbed articles from the server, it will create a
  75. file called `active' in the SLRNPULL_ROOT directory.  This `active'
  76. file will be used by the newsreader.
  77.  
  78. The SLRNPULL_ROOT directory may be specified several ways:
  79.  
  80.    1. At compile time.  The default is /var/spool/news/slrn/.
  81.    2. Via the SLRNPULL_ROOT environment variable.
  82.    3. Via the -d <dir> command line option.
  83.  
  84. In the sample script, slrnpull.sh, the third method is used.
  85.  
  86. Note: the SLRNPULL_ROOT cannot be used for multiple servers.  If you
  87. intend to use slrnpull with more than one server, you will have to set
  88. up a different tree for each server.
  89.  
  90. slrnpull command line options
  91. =============================
  92.  
  93. slrnpull may be controlled by several command line parameters:
  94.  
  95.    slrnpull <options>
  96.  
  97. where <options> can include any of the following:
  98.  
  99.    -d SLRNPULL_ROOT 
  100.    -h NNTPSERVER
  101.    --expire
  102.    --post
  103.    --new-groups
  104.  
  105. If the `-d' option is not specifed, slrnpull will attempt to determine
  106. the SLRNPULL_ROOT directory by the SLRNPULL_ROOT environment variable.
  107. If that fails, it will default to the compiled-in value.
  108.  
  109. The `-h' option controls the name of the NNTP server that will be used
  110. for pulling the news feed.  If it is not specified, slrnpull will look
  111. for the NNTPSERVER variable.
  112.  
  113. The `--expire' option is used to run slrnpull in expire mode.  If this
  114. option is specifed, no attempt will be made to access the server.  It
  115. is recommended that slrnpull be run in expire mode once every day.  It
  116. may take a few minutes to run because it causes the OVERVIEW database
  117. to be rebuilt.
  118.  
  119. The `--post' flag may be used to tell slrnpull to post any out-going
  120. articles but do not attempt pull any articles from the server.
  121. Normally this option is not required since before pulling articles
  122. because slrnpull will always post any articles in the in the out.going
  123. directory immediately before pulling new articles.
  124.  
  125. Normally slrnpull does not query the server for new groups.  The
  126. --new-groups option forces slrnpull to query the server.  If the
  127. server indicates any new groups, slrnpull will append the new group
  128. names to the file SLRNPULL_ROOT/data/new.groups and update the time
  129. stamp in the SLRNPULL_ROOT/data/new.groups-time file.
  130.  
  131. Scoring with slrnpull
  132. =====================
  133.  
  134. If slrnpull finds a file called `score' in the SLRNPULL_ROOT
  135. directory, it will read it as an slrn score file.  This file may be
  136. used to kill articles before they are pulled from the server.  The
  137. syntax of this file is identical to an ordinary slrn score file;
  138. however, any article which scores less than 0 will be killed.
  139. See the main slrn documentation for information about scoring.  A
  140. sample score file is present in this directory.
  141.  
  142.  
  143. Setting up a minimal .slrnrc file.  
  144. ==================================
  145.  
  146. Assume that the SLRNPULL_ROOT refers to the directory
  147. /var/spool/slrnpull.  Then the following .slrnrc lines should be
  148. sufficient to tell slrn how to deal with the news provided by
  149. slrnpull:
  150.  
  151.     set spool_inn_root        "/var/spool/slrnpull"
  152.     set spool_root        "/var/spool/slrnpull/news"
  153.     set spool_nov_root        "/var/spool/slrnpull/news"
  154.     set read_active        1
  155.     set use_slrnpull        1
  156.  
  157. The 'use_slrnpull' variable must be set to 1 to tell slrn to post the
  158. file to the out.going directory.  Also note that 'spool_root' and
  159. 'spool_nov_root' must be set to the same value.
  160.  
  161. In addition, it is a good idea to include the `hostname' and
  162. `username' lines, e.g.,
  163.  
  164.     hostname            "your.host.name"
  165.     username            "your.user.name"
  166.  
  167.  
  168. Some Limitations
  169. =============================================================================
  170.  
  171. Slrnpull tries to be efficient by only downloading one copy of an
  172. article that has been crossposted.  For example, if an article has
  173. been crossposted to both sci.physics and sci.astro, then if slrnpull
  174. already downloaded the article for sci.physics, it will not download
  175. the article for sci.astro.  Ideally, it should create a copy of the
  176. downloaded article in sci.astro.  This may be corrected in a future
  177. version.
  178.